﻿<html>
  <head>
    <title>Function object</title>
    <meta name="generator" content="h-smile:richtext"/>
  </head>
<body>
  <h1>Task object</h1>
  <p>Task object represents a Task - coroutine - function that can be paused at some point and returns a value. When the coroutine is called again, it is resumed right from the point it was paused and its environment remains intact.</p>
  <p>In Sciter there ar two types of coroutines:</p>
  <ul>
    <li><strong>Generator</strong> - plain function that uses <code>yield</code> statement inside.</li>
    <li><strong>Asynchronous task</strong> - plain function that uses <code>await</code> statement in its body.</li></ul>
  <h3>Task creation</h3>
  <p>To create generator or asynchronous task you define function that uses either <em>yield</em> or <em>await</em> inside:</p>
  <p>Asynchronous task:</p>
  <pre>async function getRemoteData(url) {  // Async task
   try {
       var data = await self.request(#get, url);
       return data;
   } catch (e) {
       return null;
   }
}
</pre>
  <p>Generator:</p>
  <pre>function* listItemsBackward(list) {  // Generator task
     for(var i = list.length - 1; i >= 0; --i)
       yield list[i];
}
// use of generator:
var list = [0,1,2,3];
for(var item in listItemsBackward(list))
  stdout.println(item);
</pre>

  <dl>
    <h3>Task invocation</h3>
    <p>To start Generator or Asynchronous Task you call it as any other function. The only difference from normal functions is that it completes immediately and returns Task object.</p>
    <p>The Task object holds the function, its state and represents future value that will be available either on completions of awaited statement (Asynchronous Task) or on invocation of its next() method.</p>
    <h3>Asynchronous task is a &quot;thenable&quot; thing</h3>
    <p>Asycnhronous Task object has method <code>then()</code> that matches Promise/A+ specification and so it can be treated as a promise. For examlpe, this is another asynchronous task that start two other tasks in parallel and waits for their completion:</p>
    <pre>function getRemoteDataItems()
{
 // waiting both requests to complete:
 var items = promise.when( getRemoteData(&quot;http://example.com/api/v2/item1&quot; ),
                           getRemoteData(&quot;http://example.com/api/v2/item2&quot; ));
 stdout.println(items[0],items[1]);
}
</pre>
    <h2>Properties</h2>
    <dt>isAsync</dt>
    <dd>readonly, <em>true</em> if the Task is as an active asynchronous task - awaiting competion of IO operation. Otherwise the property reports <em>false</em>.</dd>
    <dt>isGenerator</dt>
    <dd>readonly, <em>true</em> if the Task is an active (not finished) generator. Otherwise the property reports <em>false</em>.</dd>
    <h2>Methods</h2>
    <dt>then</dt>
    <dd>
      <div>( <strong>onFulfilled</strong>: function [, <strong>onRejected</strong>: function] ) : this Task</div>
      <p>adds onFulfilled and onRejected callback functions to the list of task callbacks. Either onFulfilled(result) and onRejected(error) will be called on task completion.</p>
      <p>then() method can be called on asynchronous task coroutine.</p></dd>
    <dt>catch</dt>
    <dd>
      <div>( <strong>onRejected</strong>: function ) : this Task</div>
      <p>adds onRejected callback function to the list of task callbacks. onRejected(error) will be called if task ends with error thrown.</p>
      <p>catch() method can be called only on on asynchronous task coroutine.</p>
      <p>Equivalent of <code>task.then(null, onRejected);</code> call.</p></dd>
    <dt>finally</dt>
    <dd>
      <div>( <strong>onComplete</strong>: function ) : this Task</div>
      <p>adds onComplete callback function to the list of task callbacks. onComplete(result | error) will be called on task completion.</p>
      <p>then() method can be called on asynchronous task coroutine.</p>
      <p>Equivalent of <code>task.then(onComplete, onComplete);</code> call.</p></dd>
    <dt>next</dt>
    <dd>
      <div>( [val:any] &nbsp;) : value</div>
      <p>invokes the generator function and returns value reported by yield statement in function.</p>
      <p>next() method can be called on generator coroutine only.</p></dd></dl>
</body>
</html>